#ifndef  MEM_PUB_H
#define  MEM_PUB_H

/*  mem_pub.h .... OS Main-Memory Management  */
/*  ========================================  */

/***********************************************************************
*                                                                      *
*                  Copyright Hewlett-Packard Co. 1991                  *
*                                                                      *
***********************************************************************/
/***********************************************************************
*                                                                      *
*   Module MEM -- Users Manual  (cc68xxx)                              *
*   --------------------------                                         *
*   This file defines the C-language (AxLS) interface to module MEM,   *
*   the OS main-memory manager system, (implemented in file mem.s).    *
*                                                                      *
*   NOTE:  Only those objects, (macros, constants, etc), whose names   *
*   begin with the module-prefix "MEM_" (all uppercase) are intended   *
*   for PUBLIC use;  any other objects declared in this file must be   *
*   considered PRIVATE ... and subject to change without notice.       *
*                                                                      *
*   CAUTION:  The MEM_Xxx operations manage all of main memory, they   *
*   must not be confused with the standard heap-management functions   *
*   (malloc, free, etc.) whose scope is local to the calling task.     *
*                                                                      *
*     void  *MEM_Alloc(size_t bytes)                                   *
*     ------------------------------                                   *
*       MEM_Alloc returns a pointer to an OS-memory block of the       *
*       requested size (bytes); if the request cannot be filled, a     *
*       null pointer is returned.  Pointer-alignment is compatible     *
*       with any data type;  the memory block is not initialized.      *
*                                                                      *
*     void  MEM_Free(void *p)                                          *
*     -----------------------                                          *
*       MEM_Free deallocates an OS-memory block.  If p is NULL, no     *
*       action is taken;  otherwise, p must point to a memory block    *
*       previously allocated by MEM_Alloc (but not yet deallocated).   *
*                                                                      *
*     size_t  MEM_Size(void *p)                                        *
*     -------------------------                                        *
*       MEM_Size returns the size (in bytes) of an OS-memory block.    *
*       If p is NULL, zero is returned;  otherwise, p must point to    *
*       a memory block previously allocated by MEM_Alloc (but not      *
*       yet deallocated).  Note that the reported block size may be    *
*       greater than the size originally requested from MEM_Alloc.     *
*                                                                      *
*     size_t  MEM_Init(size_t bytes, void *p)                          *
*     ---------------------------------------                          *
*       MEM_Init initializes the OS-memory manager giving it control   *
*       of a memory region whose size and base address is specified    *
*       in the calling arguments.  The returned value indicates the    *
*       size (in bytes) of the largest possible allocation block.      *
*                                                                      *
*       MEM_Init should be called only at system startup or during a   *
*       complete system re-boot;  in either case, it must be called    *
*       before any other OS-module initializations are attempted.      *
*                                                                      *
*     MEM_OVHD                                                         *
*     --------                                                         *
*       MEM_OVHD is a constant specifying memory-header "overhead";    *
*       since MEM_Alloc works with "power-of-two" physical blocks,     *
*       logical blocks of size  (2^n)-MEM_OVHD  are most efficient.    *
*                                                                      *
***********************************************************************/

/*page*/
/*  mem_pub.h .... MEM Users Manual  (continued)  */
/*  ===============================               */

/***********************************************************************
*                                                                      *
*   Module MEM -- Users Guide    !! REVISIT !!                         *
*   -------------------------                                          *
*                                                                      *
*   - "OS memory" vs "heap"  ...how to choose                          *
*                                                                      *
*   - Execution times                                                  *
*                                                                      *
*   - MEM_Alloc(bytes=0)  ...may fail  ...gives unique tokens          *
*                                                                      *
***********************************************************************/



/*page*/
/*  mem_pub.h .... OS Main-Memory Management  */
/*  ========================================  */


/***********************************
*  Include Files                   *
***********************************/

/* #include  <stddef.h>   */  /*  Get definition of size_t  */
/* #include  <typedefs.h> */  /*  Get section map for SysCode */



/***********************************
*  Symbolic Constants              *
***********************************/

  #define  MEM_OVHD  2     /* sizeof(memory-block-header) */



/***********************************
*  Operations (macros)             *
***********************************/

  #define  MEM_Alloc(n)   Mem_alloc( (n) )
  #define  MEM_Free(p)    Mem_free( (p) )
  #define  MEM_Size(p)    Mem_size( (p) )
  #define  MEM_Init(n,p)  Mem_init( (n), (p) )



/***********************************
*  Function Prototypes & Aliases   *
***********************************/

  #pragma SECTION PROG=SysCode
    extern  void   *Mem_alloc(size_t bytes);
    extern  void    Mem_free(void *p);
    extern  size_t  Mem_size(void *p);
    extern  size_t  Mem_init(size_t bytes, void *p);
  #pragma SECTION UNDO


 /*
  * Alias function names so that compiler-users may specify
  * the -l option and still have access to these operations.
  */

  #pragma  ALIAS   Mem_alloc    _Mem_alloc
  #pragma  ALIAS   Mem_free     _Mem_free
  #pragma  ALIAS   Mem_size     _Mem_size
  #pragma  ALIAS   Mem_init     _Mem_init


#endif  /* MEM_PUB_H */
